%% Introduction to building reports in IRIS
% by Petar Manchev
%
% First, create and publish an empty report to see the basic structure of
% the report package commands. Then, create anoter report with a table,
% figure, matrix, and text.

%% Clear workspace

clear;
close all;
clc;
%#ok<*NOPTS>

%% Publish Empty Report
%
% Report objects is a quick, easy and flexible tool for producing
% presentation-quality PDF reports of your results. Based on LaTeX, it
% offers a lot of typesetting functionality while keeping the syntax and
% use rather simple. Start a new report <?startNew?>, immediately publish
% the empty report to PDF <?publishEmpty?>, and open the PDF <?openEmpty?>.

x = report.new('My Empty Report'); %?startNew?

x.publish('report1.pdf', ...
    'makeTitle=',true,'display=',false); %?publishEmpty?
 
open report1.pdf; %?openEmpty?

%% Simple Report
%
% In the second example, create artificial database <?fakeData?> and use
% the following commands to combine a number of report elements within one
% report:
%
% * `table` -- Start new table in report <?table?>.
% * `figure` -- Start new figure in report <?figure?>.
% * `matrix` -- Insert matrix, or numeric array, in report <?matrix?>.
% * `text` -- Include verbatim text or LaTeX code in report.
% * `include` - Include verbatim text or LaTeX code in report from an
% external file; very convenient when creating reports with extensive
% descriptive sections.

range = qq(1990,1):qq(2010,4);

d = struct(); %?fakeData?
d.a = tseries(range,@rand);
d.b = cumsum(d.a);
d.c = diff(d.a);

% ...
%
% Start a new report object.

x = report.new('My Simple Report');

% ...
% 
% Create a table, and include two time series in the table, `d.a` and
% `d.b`.

x.table('Historical data', ... %?table?
    'range=',qq(2008,1):qq(2011,4),'dateformat=','YYYY:P');

    x.series('Series1',d.a);
    x.series('Series2',d.b,'nan=','?');

% ...
%
% Create a figure with one graph.
    
x.figure('Plot of historical data','range=',range); %?figure?

    x.graph('Series1');
        x.series('Series1',d.a);
    
% ...
%
% Insert a matrix with a title and descriptions of rows and columns.
        
x.matrix('Correlation matrix', ... %?matrix?
    rand(5), ...
    'colnames=',{'uu','vv','xx','yy','zz'}, ...
    'rownames=',{'uu','vv','xx','yy','zz'});

% ...
%
% Insert a page break, and start a new page.

x.pagebreak();


% ...
%
% Insert a text (LaTeX code) that follows immediately after the command
% `tex` in a block comment, i.e. enclosed between `%{` and `%}`.

x.tex('','centering=',false);

%{
This is a piece of text typset in \LaTeX. IRIS makes it easy to incorporate
such pieces of text in reports, verbatim and straight from an m-file.
\begin{equation} E \Psi = \hat{H} \Psi \end{equation}
%}

% ...
%
% Include the contents of a tex file in the report. First, let IRIS
% interpret the file as LaTeX code (this is the default behavior)
% <?include?>, then include the same file verbatim <?includeVerbatim?>.

x.include('','my_tex.tex','centering=',false); %?include?

x.include('','my_tex.tex','centering=',false, ...
    'verbatim=',true); %?includeVerbatim?

%% Visualise Report Structure

x

%% Publish Report to PDF
%
% When publishing the report to PDF, IRIS displays a rather long message
% produced by the LaTeX compiler by default (this can be disabled by using
% the option `'display='` as in the first example above). The function
% `publish` returns two output arguments: the name of the output PDF,
% `file`, and a struct with a few pieces of information on the report
% production process, `info` <?outputArgs?>.

disp(' ');
disp(' ');
disp('A rather long LaTeX compiler message follows...');
disp(' ');
disp(' ');

% Publish the report to a PDF.
[file,info] = x.publish('report2.pdf','maketitle=',true); %?outputArgs?

% Open the published report.
open report2.pdf;

%% Help on IRIS Functions Used in This File
%
% Use either `help` to display help in the command window, or `idoc`
% to display help in an HTML browser window.
%
%    help report
%    help report/new
%    help report/publish
%    help report/table
%    help report/series
%    help report/figure
%    help report/graph
%    help report/matrix
%    help report/pagebreak
%    help report/text
%    help report/include
